API Gatewayのドキュメントインポート時にドキュメントパーツの制限を超えたときの対処方法

いわさ

2022.06.09

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

いわさです。

API Gateway は OpenAPI / Swagger定義ファイルをインポートすることが出来ます。
APIドキュメントにはドキュメントパーツというリソースがあり、APIエンティティに提供されるドキュメントコンテンツを定義出来ます。

今回、動的パスに関するドキュメントを大量に作成してインポートしたところ、「ドキュメントパーツの制限を超えた」というエラーメッセージを受信しました。
この記事ではこの制限の確認と解決方法について紹介します。

ドキュメントパーツ

以下のようにx-amazon-apigateway-documentationでドキュメントパーツを定義することが出来ます。

{
  "swagger" : "2.0",
  "info" : {
    "version" : "2022-05-26T01:07:59Z",
    "title" : "pats1"
  },
  "host" : "cvm5zxkwhh.execute-api.ap-northeast-1.amazonaws.com",
  "basePath" : "/hoge",
  "schemes" : [ "https" ],
  "paths" : {

:

  },
  "definitions" : {
    "Empty" : {
      "type" : "object",
      "title" : "Empty Schema"
    }
  },
  "x-amazon-apigateway-documentation" : {
    "version" : "v1",
    "createdDate" : "2022-05-26T01:16:11Z",
    "documentationParts" : [ {
      "location" : {
        "type" : "MODEL",
        "name" : "Empty"
      },
      "properties" : {
        "title" : "Empty Schema"
      }
    }, {
      "location" : {
        "type" : "RESOURCE",
        "path" : "/1"
      },
      "properties" : {
        "description" : "1"
      }
    }, {
      "location" : {
        "type" : "RESOURCE",
        "path" : "/2"
      },
      "properties" : {
        "description" : "2"
      }
    }, {
      "location" : {
        "type" : "RESPONSE",
        "method" : "GET",
        "statusCode" : "200"
      },
      "properties" : {
        "description" : "200 response"
      }
    } ]
  }
}

そして、API Gatewayコンソールからこのドキュメントをインポートすることが出来ます。

大量パーツとエラー

今回、以下のようにドキュメントパーツ部分が2500ほどになりました。
一点注意点があって、この記事ではドキュメント設計としての良し悪しについて言及するものではないので、そもそも大量のドキュメントパーツを定義するべきではないみたいなところは言及しません。こういったエラーが起きたときにドキュメントを見直す以外にどういう対処をしたら良いのかを紹介したいと思っています。

{
    "swagger" : "2.0",
    "info" : {
      "version" : "2022-05-26T01:07:59Z",
      "title" : "pats1"
    },
    "host" : "cvm5zxkwhh.execute-api.ap-northeast-1.amazonaws.com",
    "basePath" : "/hoge",
    "schemes" : [ "https" ],
    "paths" : {
      "/" : {
        "get" : {
          "produces" : [ "application/json" ],
          "responses" : {
            "200" : {
              "description" : "200 response",
              "schema" : {
                "$ref" : "#/definitions/Empty"
              }
            }
          },
          "x-amazon-apigateway-integration" : {
            "httpMethod" : "GET",
            "uri" : "https://classmethod.jp/",
            "responses" : {
              "default" : {
                "statusCode" : "200"
              }
            },
            "passthroughBehavior" : "when_no_match",
            "type" : "http_proxy"
          }
        }
      }
    },
    "definitions" : {
      "Empty" : {
        "type" : "object",
        "title" : "Empty Schema"
      }
    },
    "x-amazon-apigateway-documentation" : {
      "version" : "v1",
      "createdDate" : "2022-05-26T01:16:11Z",
      "documentationParts" : [
        {"location" : {"type" : "RESPONSE", "method" : "GET", "statusCode" : "200"}, "properties" : {"description" : "200 response"}},
        {"location" : {"type" : "MODEL", "name" : "Empty"}, "properties" : {"title" : "Empty Schema"}},
        {"location" : {"type" : "RESOURCE", "path" : "/1"}, "properties" : {"description" : "1"}},
        {"location" : {"type" : "RESOURCE", "path" : "/2"}, "properties" : {"description" : "2"}}, 
        {"location" : {"type" : "RESOURCE", "path" : "/3"}, "properties" : {"description" : "3"}},
        {"location" : {"type" : "RESOURCE", "path" : "/4"}, "properties" : {"description" : "4"}},
        {"location" : {"type" : "RESOURCE", "path" : "/5"}, "properties" : {"description" : "5"}},

:

        {"location" : {"type" : "RESOURCE", "path" : "/2497"}, "properties" : {"description" : "2497"}},
        {"location" : {"type" : "RESOURCE", "path" : "/2498"}, "properties" : {"description" : "2498"}},
        {"location" : {"type" : "RESOURCE", "path" : "/2499"}, "properties" : {"description" : "2499"}},
        {"location" : {"type" : "RESOURCE", "path" : "/2500"}, "properties" : {"description" : "2500"}}
      ]
    }
  }

この大量のドキュメントパーツを含むドキュメントをインポートしてみます。

思ってたよりインポートの結果が出る時間はかからないです。
私が確認した際には画面上はエラー通知も完了通知も何も表示されませんでした。しかし取り込みはされていません。

CloudTrailを見てみると、エラー内容を確認することが出来ます。
以下のエラーが発生しています。

Warnings found during import:
Unable to import documentation parts from the Swagger file because it contains more documentation parts than the maximum number allowed for this API. Please contact AWS if you need additional documentation parts.

{
    "eventVersion": "1.08",
    "userIdentity": {

:

    },
    "eventTime": "2022-05-26T01:30:49Z",
    "eventSource": "apigateway.amazonaws.com",
    "eventName": "ImportDocumentationParts",
    "awsRegion": "ap-northeast-1",
    "sourceIPAddress": "AWS Internal",
    "userAgent": "AWS Internal",
    "errorCode": "BadRequestException",
    "errorMessage": "Warnings found during import:\n\tUnable to import documentation parts from the Swagger file because it contains more documentation parts than the maximum number allowed for this API. Please contact AWS if you need additional documentation parts.",
    "requestParameters": {
        "omitted": true,
        "originalSize": 883383,
        "reason": "requestParameters too large"
    },
    "responseElements": null,
    "requestID": "1228b1b0-47ab-4163-a2a8-af381d9d0c8e",
    "eventID": "b68e623d-4747-4a19-9696-a4148839354c",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "sessionCredentialFromConsole": "true"
}